#ifndef LV_TIMER_H
#define LV_TIMER_H

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

/* 定时器回调函数类型
 * 参数：用户自定义数据
 * 返回值：下一次触发的延时时间（毫秒），返回0表示不再触发（单次模式）
 */
typedef uint32_t (*lv_timer_cb_t)(void *user_data);

/* 定时器结构体（用户无需直接操作成员） */
typedef struct lv_timer {
    struct lv_timer *next;       /* 链表节点：用于连接多个定时器 */
    lv_timer_cb_t cb;            /* 定时回调函数 */
    void *user_data;             /* 用户自定义数据 */
    uint32_t period;             /* 定时周期（毫秒，用于周期模式） */
    uint32_t remaining;          /* 剩余时间（毫秒，递减至0触发） */
    bool is_repeat;              /* 是否周期触发：true=周期，false=单次 */
    bool active;                 /* 激活状态：true=运行中，false=已停止 */
} lv_timer_t;

/* 初始化定时器模块
 * 需在使用任何定时器功能前调用
 */
void lv_timer_init(void);

/* 创建定时器
 * 参数：
 *   cb：回调函数
 *   period：定时周期（毫秒）
 *   user_data：用户数据
 *   is_repeat：是否周期触发（true=周期，false=单次）
 * 返回值：
 *   成功：定时器指针；失败：NULL（内存不足）
 */
lv_timer_t *lv_timer_create(lv_timer_cb_t cb, uint32_t period, void *user_data, bool is_repeat);

/* 启动定时器
 * 参数：timer：要启动的定时器
 * 说明：启动后定时器加入调度链表，开始计时
 */
void lv_timer_start(lv_timer_t *timer);

/* 停止定时器
 * 参数：timer：要停止的定时器
 * 说明：停止后定时器从调度链表移除，不再触发
 */
void lv_timer_stop(lv_timer_t *timer);

/* 删除定时器
 * 参数：timer：要删除的定时器
 * 说明：释放定时器占用的内存，删除前会自动停止
 */
void lv_timer_del(lv_timer_t *timer);

/* 定时器心跳函数
 * 参数：elapsed_ms：自上次调用以来的毫秒数（必须>0）
 * 说明：需由硬件定时器或系统滴答定时器周期性调用，推荐1-10ms调用一次
 */
void lv_timer_handler(uint32_t elapsed_ms);

#endif